SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_perl.idb/usr/freeware/catman/p_man/cat3/Tie::Array.Z/Tie::Array

Text File | 1998-10-28 | 6.9 KB | 265 lines

     TTTTiiiieeee::::::::AAAArrrrrrrraaaayyyy((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     TTTTiiiieeee::::::::AAAArrrrrrrraaaayyyy((((3333))))



     NNNNAAAAMMMMEEEE
      Tie::Array - base class for tied arrays

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          package NewArray;
          use Tie::Array;
          @ISA = ('Tie::Array');

          #    mandatory methods
          sub TIEARRAY { ... }
          sub FETCH    { ... }
          sub FETCHSIZE { ... }

          sub STORE    { ... }           # mandatory if elements writeable
          sub STORESIZE { ... }    # mandatory if elements can be added/deleted

          #    optional methods - for efficiency
          sub CLEAR    { ... }
          sub PUSH { ... }
          sub POP {    ... }
          sub SHIFT    { ... }
          sub UNSHIFT { ...    }
          sub SPLICE { ... }
          sub EXTEND { ... }
          sub DESTROY { ...    }

          package NewStdArray;
          use Tie::Array;

          @ISA = ('Tie::StdArray');

          #    all methods provided by    default

          package main;

          $object =    tie @somearray,Tie::NewArray;
          $object =    tie @somearray,Tie::StdArray;
          $object =    tie @somearray,Tie::NewStdArray;


     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      This module provides methods for array-tying classes.    See
      the _p_e_r_l_t_i_e manpage for a list of the    functions required in
      order    to tie an array    to a package. The basic    TTTTiiiieeee::::::::AAAArrrrrrrraaaayyyy
      package provides stub    DELETE and EXTEND methods, and
      implementations of PUSH, POP,    SHIFT, UNSHIFT,    SPLICE and
      CLEAR    in terms of basic FETCH, STORE,    FETCHSIZE, STORESIZE.

      The TTTTiiiieeee::::::::SSSSttttddddAAAArrrrrrrraaaayyyy package provides efficient methods
      required for tied arrays which are implemented as blessed
      references to    an "inner" perl    array.    It inherits from
      TTTTiiiieeee::::::::AAAArrrrrrrraaaayyyy, and should cause tied arrays to behave exactly



     Page 1                        (printed 10/23/98)






     TTTTiiiieeee::::::::AAAArrrrrrrraaaayyyy((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     TTTTiiiieeee::::::::AAAArrrrrrrraaaayyyy((((3333))))



      like standard    arrays,    allowing for selective overloading of
      methods.

      For developers wishing to write their    own tied arrays, the
      required methods are briefly defined below. See the the
      _p_e_r_l_t_i_e manpage section for more detailed descriptive, as
      well as example code:

      TIEARRAY classname, LIST
           The class method    is invoked by the command tie @array,
           classname. Associates an    array instance with the
           specified class.    LIST would represent additional
           arguments (along    the lines of the _A_n_y_D_B_M__F_i_l_e manpage
           and compatriots)    needed to complete the association.
           The method should return    an object of a class which
           provides    the methods below.

      STORE    this, index, value
           Store datum _v_a_l_u_e into _i_n_d_e_x for    the tied array
           assoicated with object _t_h_i_s. If this makes the array
           larger then class's mapping of undef should be returned
           for new positions.

      FETCH    this, index
           Retrieve    the datum in _i_n_d_e_x for the tied    array
           assoicated with object _t_h_i_s.

      FETCHSIZE this
           Returns the total number    of items in the    tied array
           assoicated with object _t_h_i_s. (Equivalent    to
           scalar(@array)).

      STORESIZE this, count
           Sets the    total number of    items in the tied array
           assoicated with object _t_h_i_s to be _c_o_u_n_t.    If this    makes
           the array larger    then class's mapping of    undef should
           be returned for new positions.  If the array becomes
           smaller then entries beyond count should    be deleted.

      EXTEND this, count
           Informative call    that array is likely to    grow to    have
           _c_o_u_n_t entries.  Can be used to optimize allocation.
           This method need    do nothing.

      CLEAR    this
           Clear (remove, delete, ...) all values from the tied
           array assoicated    with object _t_h_i_s.

      DESTROY this
           Normal object destructor    method.





     Page 2                        (printed 10/23/98)






     TTTTiiiieeee::::::::AAAArrrrrrrraaaayyyy((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     TTTTiiiieeee::::::::AAAArrrrrrrraaaayyyy((((3333))))



      PUSH this, LIST
           Append elements of LIST to the array.

      POP this
           Remove last element of the array    and return it.

      SHIFT    this
           Remove the first    element    of the array (shifting other
           elements    down) and return it.

      UNSHIFT this,    LIST
           Insert LIST elements at the begining of the array,
           moving existing elements    up to make room.

      SPLICE this, offset, length, LIST
           Perform the equivalent of splice    on the array.

           _o_f_f_s_e_t is optional and defaults to zero,    negative
           values count back from the end of the array.

           _l_e_n_g_t_h is optional and defaults to rest of the array.

           _L_I_S_T may    be empty.

           Returns a list of the original _l_e_n_g_t_h elements at
           _o_f_f_s_e_t.

     CCCCAAAAVVVVEEEEAAAATTTTSSSS
      There    is no support at present for tied @ISA.    There is a
      potential conflict between magic entries needed to notice
      setting of @ISA, and those needed to implement 'tie'.

      Very little consideration has    been given to the behaviour of
      tied arrays when $[ is not default value of zero.

     AAAAUUUUTTTTHHHHOOOORRRR
      Nick Ing-Simmons <[e-mail]>


















     Page 3                        (printed 10/23/98)






     TTTTiiiieeee::::::::AAAArrrrrrrraaaayyyy((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     TTTTiiiieeee::::::::AAAArrrrrrrraaaayyyy((((3333))))























































     Page 4                        (printed 10/23/98)